home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2005 October / PCWOCT05.iso / Software / FromTheMag / XAMPP 1.4.14 / xampp-win32-1.4.14-installer.exe / xampp / webalizer / DNS.README < prev    next >
Text File  |  2002-04-23  |  9KB  |  186 lines
  1. The Webalizer - A log file analysis program  -- DNS information
  2.  
  3. The webalizer now has the ability to perform reverse DNS lookups.  This
  4. document attempts to explain how it works and some things that you should
  5. be aware of when using the DNS lookup features.
  6.  
  7. Note: The Reverse DNS feature may be enabled or disabled at compile
  8.       time.  It is enabled by using the -DUSE_DNS compiler switch, or
  9.       by specifing '--enable-dns' when "configure' is run.  DNS lookups
  10.       are disabled by default.
  11.       
  12. Another Note: DNS lookups will not work under Windows yet, see the
  13.       README.WIN file for more information.
  14.  
  15.  
  16. How it works
  17. ------------
  18.  
  19. DNS lookups are made against a DNS cache file containing IP addresses
  20. and resolved names.  If the IP address is not found in the cache file,
  21. it will be left as an IP address.  In order for this to happen, a
  22. cache file MUST be specified when the Webalizer is run, either using
  23. the '-D' command line switch, or a "DNSCache" configuration file
  24. keyword.  If no cache file is specified, no attempts to perform DNS
  25. lookups will be done. The cache file can be made in two different ways.
  26.  
  27. 1) You can have the Webalizer pre-process the specified log file at
  28.    run-time, creating the cache file before processing the log file
  29.    normally.  This is done by setting the number of DNS Children
  30.    processes to run, either by using the '-N' command line switch or
  31.    the "DNSChildren" configuration keyword.  This will cause the
  32.    Webalizer to spawn the specified number of processes which will
  33.    be used to do reverse DNS lookups.. generally, a larger number
  34.    of processes will result in faster resolution of the log, however
  35.    if set too high may cause overall system degredation.  A setting
  36.    of between 5 and 20 should be acceptable, and there is a maximum
  37.    limit of 100.   If used, a cache filename MUST be specified also,
  38.    using either the '-D' command line switch, or the "DNSCache"
  39.    configuration keyword.  Using this method, normal processing will
  40.    continue only after all IP addresses have been processed, and the
  41.    cache file is created/updated.
  42.  
  43. 2) You can pre-process the log file as a standalone process, creating
  44.    the cache file that will be used later by the Webalizer.  This is
  45.    done by running the Webalizer with a name of 'webazolver' (ie: the
  46.    name 'webazolver' is a symbolic link to 'webalizer') and specifing
  47.    the cache filename (either with '-D' or DNSCache).   If the number
  48.    of child processes is not given, the default of 5 will be used. In
  49.    this mode, the log will be read and processed, creating a DNS cache
  50.    file or updating an existing one, and the program will then exit
  51.    without any further processing.
  52.  
  53.  
  54. Run-time DNS cache file creation/update
  55. ---------------------------------------
  56.  
  57. The creation/update of a DNS cache file at run-time occurs as follows:
  58.  
  59. 1) The log file is read, creating a list of all IP addresses that are
  60.    not already cached and need to be resolved.
  61.  
  62. 2) The specified number of children processes are forked, and are used
  63.    to perform DNS lookups.
  64.  
  65. 3) Each IP address is given, one at a time, to the next available child
  66.    process until all IP addresses have been processed.  Each child will
  67.    update the cache file when a name is found.
  68.  
  69. 4) Once all IP addresses have been processed and the cache file updated,
  70.    the Webalizer will process the log normally.  Each record it finds
  71.    that has an unresolved IP address will be looked up in the cache file
  72.    to see if a hostname is available (ie: was previously found).
  73.  
  74. Because there may be a significant amount of time between the inital
  75. unresolved IP list and normal processing, the Webalizer should not be
  76. run against live log files (ie: a log file that is activly being written
  77. to by a server), otherwise there may be additional records present that
  78. were not resolved.
  79.  
  80.  
  81. Stand-Alone DNS cache file creation/update
  82. ------------------------------------------
  83.  
  84. The creation/update of the DNS cache file, when run in stand-alone mode,
  85. occurs as follows:
  86.  
  87. 1) The log file is read, creating a list of all IP addresses that are
  88.    not already cached and need to be resolved.
  89.  
  90. 2) The specified number of children processes are forked, and are used
  91.    to perform DNS lookups.  If the number of processes was not specified,
  92.    the default of 5 will be used.
  93.  
  94. 3) Each IP address is given, one at a time, to the next available child
  95.    process until all IP addresses have been processed.  Each child will
  96.    update the cache file when a name is found.
  97.  
  98. 4) Once all IP addresses have been processed and the cache file updated,
  99.    the program will terminate without any further processing.
  100.  
  101.  
  102. Larger sites may prefer to use a stand-alone process to create the DNS
  103. cache file, and then run the Webalizer against the cache file.  This
  104. allows a single cache file to be used for many virtual hosts, and reduces
  105. the processing needed if many sites are being processed.  The Webalizer
  106. can be used in stand alone mode by running it as 'webazolver'.  When
  107. run in this fashion, it will only create the cache file and then exit
  108. without any further processing.  A cache filename MUST be specified,
  109. however unlike when running the Webalizer normally, the number of child
  110. processes does not have to be given (will default to 5).  All normal
  111. configuration and command line options are recognized, however, many
  112. of them will simply be ignored.. this allows the use of a standard
  113. configuration file for both normal use and stand alone use.
  114.  
  115.  
  116. Examples:
  117. ---------
  118.  
  119. webalizer -c test.conf -N 10 -D dns_cache.db /var/log/my_www_log
  120.  
  121.    This will use the configuration file 'test.conf' to obtain normal
  122.    configuration options such as hostname and output directory.. it
  123.    will then either create or update the file 'dns_cache.db' in the
  124.    default output directory (using 10 child processes) based on the
  125.    IP addresses it finds in the log /var/lib/my_www_log, and then
  126.    process that log file normally.
  127.  
  128.  
  129. webalizer -o out -D dns_cache.db /var/log/my_www_log
  130.  
  131.   This will process the log file /var/log/my_www_log, resolving IP
  132.   addresses from the cache file 'dns_cache.db' found in the default
  133.   output directory "out".  The cache file must be present as it will
  134.   not be created with this command.
  135.  
  136.  
  137. for i in /var/log/*/access_log; do
  138.   webazolver -N 20 -D /var/lib/dns_cache.db $i
  139. done
  140.  
  141.   The above is an example of how to run through multiple log files
  142.   creating a single DNS cache file.. this might be typically used on
  143.   a larger site that has many virtual hosts, all keeping their log
  144.   files in a seperate directory.  It will process each access_log it
  145.   finds in /var/log/* and create a cache file (var/lib/dns_cache.db).
  146.   This cache file can then be used to process the logs normally with
  147.   with the Webalizer.
  148.  
  149.  
  150. for i in /etc/webalizer/*.conf; do webalizer -c $i -D /etc/cache.db; done
  151.  
  152.   This will process each configuration file found in /etc/webalizer,
  153.   using the DNS cache file /etc/cache.db.  This will also typically be
  154.   used on a larger site with multiple hosts..  Each configration file
  155.   will specify a site specific log file, hostname, output directory, etc.
  156.   The cache file used will typically be created using a command similar
  157.   to the one previous to this example.
  158.  
  159.  
  160. Considerations
  161. --------------
  162.  
  163. Processing of live log files is discouraged, as the chances of log records
  164. being written between the time of DNS resolution and normal processing will
  165. cause problems.
  166.  
  167. Cached DNS addresses have a TTL (time to live) of 3 days.  This may be
  168. changed at compile time by editing the dns_resolv.h header file and
  169. changing the value for DNS_CACHE_TTL.
  170.  
  171. There is an absolute maximum of 100 child processes that may be created,
  172. however the actual number of children should be significantly less than
  173. the maximum.. typical usage should be between 5 and 20.
  174.  
  175. If you are using STDIN for the input stream (log file) and have run-time
  176. DNS cache file creation/update enabled.. the program will exit after the
  177. cache file has been created/updated and no output will be produced.  If
  178. you must use STDIN for the input log, you will need to process the stream
  179. twice, once to create/update the cache file, and again to produce the
  180. reports.
  181.  
  182. Special thanks to Henning P. Schmiedehausen <hps@tanstaafl.de> for the
  183. original dns-resolver code he submitted,  which was the basis for this
  184. implementation.
  185.  
  186.